<a href='https://github.com/angular/angular.js/edit/v1.6.x/docs/content/guide/filter.ngdoc?message=docs(guide%2FFilters)%3A%20describe%20your%20change...' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit">&nbsp;</i>Improve this Doc</a>


<h1 id="filters">Filters</h1>
<p>Filters format the value of an expression for display to the user. They can be used in view
templates, controllers or services. Angular comes with a collection of
<a href="api/ng/filter">built-in filters</a>, but it is easy to define your own as well.</p>
<p>The underlying API is the <a href="api/ng/provider/$filterProvider"><code>$filterProvider</code></a>.</p>
<h2 id="using-filters-in-view-templates">Using filters in view templates</h2>
<p>Filters can be applied to expressions in view templates using the following syntax:</p>
<pre><code>{{ expression | filter }}
</code></pre>
<p>E.g. the markup <code>{{ 12 | currency }}</code> formats the number 12 as a currency using the <a href="api/ng/filter/currency"><code>currency</code></a>
filter. The resulting value is <code>$12.00</code>.</p>
<p>Filters can be applied to the result of another filter. This is called &quot;chaining&quot; and uses
the following syntax:</p>
<pre><code>{{ expression | filter1 | filter2 | ... }}
</code></pre>
<p>Filters may have arguments. The syntax for this is</p>
<pre><code>{{ expression | filter:argument1:argument2:... }}
</code></pre>
<p>E.g. the markup <code>{{ 1234 | number:2 }}</code> formats the number 1234 with 2 decimal points using the
<a href="api/ng/filter/number"><code>number</code></a> filter. The resulting value is <code>1,234.00</code>.</p>
<h3 id="when-filters-are-executed">When filters are executed</h3>
<p>In templates, filters are only executed when their inputs have changed. This is more performant than executing
a filter on each <a href="api/ng/type/$rootScope.Scope#$digest"><code>$digest</code></a> as is the case with <a href="guide/expression">expressions</a>.</p>
<p>There are two exceptions to this rule:</p>
<ol>
<li><p>In general, this applies only to filters that take <a href="https://developer.mozilla.org/docs/Glossary/Primitive">primitive values</a>
as inputs. Filters that receive <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Objects">Objects</a>
as input are executed on each <code>$digest</code>, as it would be too costly to track if the inputs have changed.</p>
</li>
<li><p>Filters that are marked as <code>$stateful</code> are also executed on each $digest.
See <a href="guide/filter#stateful-filters">Stateful filters</a> for more information. Note that no Angular
core filters are $stateful.</p>
</li>
</ol>
<h2 id="using-filters-in-controllers-services-and-directives">Using filters in controllers, services, and directives</h2>
<p>You can also use filters in controllers, services, and directives.</p>
<div class="alert alert-info">
For this, inject a dependency with the name <code>&lt;filterName&gt;Filter</code> into your controller/service/directive.
E.g. a filter called <code>number</code> is injected by using the dependency <code>numberFilter</code>. The injected argument
is a function that takes the value to format as first argument, and filter parameters starting with the second argument.
</div>

<p>The example below uses the filter called <a href="api/ng/filter/filter"><code>filter</code></a>.
This filter reduces arrays into sub arrays based on
conditions. The filter can be applied in the view template with markup like
<code>{{ctrl.array | filter:&#39;a&#39;}}</code>, which would do a fulltext search for &quot;a&quot;.
However, using a filter in a view template will reevaluate the filter on
every digest, which can be costly if the array is big.</p>
<p>The example below therefore calls the filter directly in the controller.
By this, the controller is able to call the filter only when needed (e.g. when the data is loaded from the backend
or the filter expression is changed).</p>
<p>

<div>
  <plnkr-opener example-path="examples/example-filter-in-controller"></plnkr-opener>

  <div class="runnable-example"
      path="examples/example-filter-in-controller"
      module="FilterInControllerModule"
      name="filter-in-controller">

  
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div ng-controller=&quot;FilterController as ctrl&quot;&gt;&#10;  &lt;div&gt;&#10;    All entries:&#10;    &lt;span ng-repeat=&quot;entry in ctrl.array&quot;&gt;{{entry.name}} &lt;/span&gt;&#10;  &lt;/div&gt;&#10;  &lt;div&gt;&#10;    Entries that contain an &quot;a&quot;:&#10;    &lt;span ng-repeat=&quot;entry in ctrl.filteredArray&quot;&gt;{{entry.name}} &lt;/span&gt;&#10;  &lt;/div&gt;&#10;&lt;/div&gt;</code></pre>
    </div>
  
    <div class="runnable-example-file" 
      name="script.js"
      language="js"
      type="js">
      <pre><code>angular.module(&#39;FilterInControllerModule&#39;, []).&#10;controller(&#39;FilterController&#39;, [&#39;filterFilter&#39;, function FilterController(filterFilter) {&#10;  this.array = [&#10;    {name: &#39;Tobias&#39;},&#10;    {name: &#39;Jeff&#39;},&#10;    {name: &#39;Brian&#39;},&#10;    {name: &#39;Igor&#39;},&#10;    {name: &#39;James&#39;},&#10;    {name: &#39;Brad&#39;}&#10;  ];&#10;  this.filteredArray = filterFilter(this.array, &#39;a&#39;);&#10;}]);</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" ng-src="{{getExampleIndex('examples/example-filter-in-controller')}}" name="example-filter-in-controller"></iframe>
  </div>
</div>


</p>
<h2 id="creating-custom-filters">Creating custom filters</h2>
<p>Writing your own filter is very easy: just register a new filter factory function with
your module. Internally, this uses the <a href="api/ng/provider/$filterProvider"><code>filterProvider</code></a>.
This factory function should return a new filter function which takes the input value
as the first argument. Any filter arguments are passed in as additional arguments to the filter
function.</p>
<p>The filter function should be a <a href="http://en.wikipedia.org/wiki/Pure_function">pure function</a>, which
means that it should always return the same result given the same input arguments and should not affect
external state, for example, other Angular services. Angular relies on this contract and will by default
execute a filter only when the inputs to the function change.
<a href="guide/filter#stateful-filters">Stateful filters</a> are possible, but less performant.</p>
<div class="alert alert-warning">
<strong>Note:</strong> Filter names must be valid angular <a href="guide/expression"><code>Expressions</code></a> identifiers, such as <code>uppercase</code> or <code>orderBy</code>.
Names with special characters, such as hyphens and dots, are not allowed.  If you wish to namespace
your filters, then you can use capitalization (<code>myappSubsectionFilterx</code>) or underscores
(<code>myapp_subsection_filterx</code>).
</div>

<p>The following sample filter reverses a text string. In addition, it conditionally makes the
text upper-case.</p>
<p>

<div>
  <plnkr-opener example-path="examples/example-filter-reverse"></plnkr-opener>

  <div class="runnable-example"
      path="examples/example-filter-reverse"
      module="myReverseFilterApp"
      name="filter-reverse">

  
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div ng-controller=&quot;MyController&quot;&gt;&#10;  &lt;input ng-model=&quot;greeting&quot; type=&quot;text&quot;&gt;&lt;br&gt;&#10;  No filter: {{greeting}}&lt;br&gt;&#10;  Reverse: {{greeting|reverse}}&lt;br&gt;&#10;  Reverse + uppercase: {{greeting|reverse:true}}&lt;br&gt;&#10;  Reverse, filtered in controller: {{filteredGreeting}}&lt;br&gt;&#10;&lt;/div&gt;</code></pre>
    </div>
  
    <div class="runnable-example-file" 
      name="script.js"
      language="js"
      type="js">
      <pre><code>angular.module(&#39;myReverseFilterApp&#39;, [])&#10;.filter(&#39;reverse&#39;, function() {&#10;  return function(input, uppercase) {&#10;    input = input || &#39;&#39;;&#10;    var out = &#39;&#39;;&#10;    for (var i = 0; i &lt; input.length; i++) {&#10;      out = input.charAt(i) + out;&#10;    }&#10;    // conditional based on optional argument&#10;    if (uppercase) {&#10;      out = out.toUpperCase();&#10;    }&#10;    return out;&#10;  };&#10;})&#10;.controller(&#39;MyController&#39;, [&#39;$scope&#39;, &#39;reverseFilter&#39;, function($scope, reverseFilter) {&#10;  $scope.greeting = &#39;hello&#39;;&#10;  $scope.filteredGreeting = reverseFilter($scope.greeting);&#10;}]);</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" ng-src="{{getExampleIndex('examples/example-filter-reverse')}}" name="example-filter-reverse"></iframe>
  </div>
</div>


</p>
<h3 id="stateful-filters">Stateful filters</h3>
<p>It is strongly discouraged to write filters that are stateful, because the execution of those can&#39;t
be optimized by Angular, which often leads to performance issues. Many stateful filters can be
converted into stateless filters just by exposing the hidden state as a model and turning it into an
argument for the filter.</p>
<p>If you however do need to write a stateful filter, you have to mark the filter as <code>$stateful</code>, which
means that it will be executed one or more times during the each <code>$digest</code> cycle.</p>
<p>

<div>
  <plnkr-opener example-path="examples/example-filter-stateful"></plnkr-opener>

  <div class="runnable-example"
      path="examples/example-filter-stateful"
      module="myStatefulFilterApp"
      name="filter-stateful">

  
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div ng-controller=&quot;MyController&quot;&gt;&#10;  Input: &lt;input ng-model=&quot;greeting&quot; type=&quot;text&quot;&gt;&lt;br&gt;&#10;  Decoration: &lt;input ng-model=&quot;decoration.symbol&quot; type=&quot;text&quot;&gt;&lt;br&gt;&#10;  No filter: {{greeting}}&lt;br&gt;&#10;  Decorated: {{greeting | decorate}}&lt;br&gt;&#10;&lt;/div&gt;</code></pre>
    </div>
  
    <div class="runnable-example-file" 
      name="script.js"
      language="js"
      type="js">
      <pre><code>angular.module(&#39;myStatefulFilterApp&#39;, [])&#10;.filter(&#39;decorate&#39;, [&#39;decoration&#39;, function(decoration) {&#10;&#10;  function decorateFilter(input) {&#10;    return decoration.symbol + input + decoration.symbol;&#10;  }&#10;  decorateFilter.$stateful = true;&#10;&#10;  return decorateFilter;&#10;}])&#10;.controller(&#39;MyController&#39;, [&#39;$scope&#39;, &#39;decoration&#39;, function($scope, decoration) {&#10;  $scope.greeting = &#39;hello&#39;;&#10;  $scope.decoration = decoration;&#10;}])&#10;.value(&#39;decoration&#39;, {symbol: &#39;*&#39;});</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" ng-src="{{getExampleIndex('examples/example-filter-stateful')}}" name="example-filter-stateful"></iframe>
  </div>
</div>


</p>
<h2 id="testing-custom-filters">Testing custom filters</h2>
<p>See the <a href="http://docs.angularjs.org/tutorial/step_11#testing">phonecat tutorial</a> for an example.</p>


